\section{JEdifNMRSelection}
JEdifNMRSelection determines which parts of a design will be
replicated. This executable can be run in multiple passes to select
different parts of a design for different kinds of replication. Each
run of JEdifNMRSelection can select portions of a design for a single
replication type (i.e. duplication, replication). Design partitions can
be selected for replication based on available space or specific cell
types, instances, ports, and clock domains specified by the user. The
results of JEdifNMRSelection are saved in a replication description
(.rdesc) file. This file can be modified by subsequent runs of this
and other executables in the toolflow.

See Section~\ref{sec:nmr_selection_examples} for examples of JEdifNMRSelection
usage in common scenarios.

\begin{verbatim}
>java edu.byu.ece.edif.jedif.JEdifNMRSelection
Options:

  [-h|--help]
  [-v|--version]

  <input_file>
  (-r|--rep_desc) <rep_desc>
  (-c|--c_desc) <c_desc>

  --replication_type <replication_type>
  [--continue]
  [--override]

  [--full_nmr]
  [--no_partial_nmr]
  [--nmr_p Port name1,Port name2,...,Port nameN ]
  [--nmr_inports]
  [--nmr_outports]
  [--no_nmr_p port1,port2,...,portN ]
  [--nmr_c cell_type1,cell_type2,...,cell_typeN ]
  [--nmr_clk clock_domain1,clock_domain2,...,clock_domainN ]
  [--nmr_i cell_instance1,cell_instance2,...,cell_instanceN ]
  [--no_nmr_c cell_type1,cell_type2,...,cell_typeN ]
  [--no_nmr_clk clock_domain1,clock_domain2,...,clock_domainN ]
  [--no_nmr_i cell_instance1,cell_instance2,...,cell_instanceN ]
  [--no_nmr_feedback]
  [--no_nmr_input_to_feedback]
  [--no_nmr_feedback_output]
  [--no_nmr_feed_forward]
  [--scc_sort_type <{1|2|3}>]
  [--do_scc_decomposition]
  [--input_addition_type <{1|2|3}>]
  [--output_addition_type <{1|2|3}>]

  [--merge_factor <merge_factor>]
  [--optimization_factor <optimization_factor>]
  [--factor_type <{DUF|UEF|ASUF|CF}>]
  [--factor_value <factor_value>]
  [--ignore_hard_resource_utilization_limits]
  [--ignore_soft_logic_utilization_limit]

  [(-p|--part) <part>]

  [--write_config <config_file>]
  [--use_config <config_file>]

  [--log <logfile>]
  [--debug[:<debug_log>]]
  [(-V|--verbose) <{1|2|3|4|5}>]
  [--append_log]
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{File Options}

\subsubsection{\texttt{<input\_file>}}
Filename and path to the jedif source file to be replicated.

\subsubsection{\texttt{(-r|--rep\_desc) <rep\_desc>}}
Filename and path to the replication description (.rdesc) file to be written.
The file will be modified by subsequent runs of JEdifNMRSelection when the
\texttt{--continue} option is used.

\subsubsection{\texttt{(-c|--c\_desc) <c\_desc>}}
Filename and path to the circuit description (.cdesc) file generated by
JEdifAnalyze.

\subsection{Replication Type Options}

\subsubsection{\texttt{--replication\_type <replication\_type>}}
Replication type to use for this run. Must be one of \texttt{triplication} or
\texttt{duplication}.

\subsubsection{\texttt{--continue}}
Select this option to build selection results on top of results from previous
runs. If not selected, the replication description file (.rdesc) will be
overwritten completely instead of just modified. Normally, when continuing NMR
selection with this flag, only instances that have not yet been selected for a
replication type will be considered. Overriding replication types for instances
and ports can be accomplished by using the \texttt{--override} flag in
conjunction with this flag.

\subsubsection{\texttt{--override}}
This flag may be used in conjunction with the \texttt{--continue} flag in order
to override the replication type selections for instances that have already been
selected.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Partial Replication Options}

\subsubsection{\texttt{--full\_nmr}}
Fully replicate the design, skipping all partial replication analysis. This
method is preferred when the design is expected to fit in the target part with
full replication of every resource since some time-consuming algorithms are skipped.
Resource utilization estimates will still function, stopping replication and 
warning the user if the full replicated design is not expected to fit in the 
target part.

Note: \texttt{--full\_nmr} will replicate all logic within the design; however, 
top-level ports are not replicated by default. To replicate top-level ports,
use the \texttt{--nmr\_inports} and \texttt{--nmr\_outports} options.

\subsubsection{\texttt{--no\_partial\_nmr}}
This option will disable the use of partial NMR analysis to determine which
parts of the circuit to replicate. Use this option in conjuction with the
\texttt{--nmr\_i} and \texttt{--nmr\_c} options for explicit control of
replicated instances. This option need not be used when the \texttt{--full\_nmr}
option is used.

\subsubsection{\texttt{--nmr\_p port1,port2,\ldots,port3}}
Comma-separated list of ports to be replicated.

\subsubsection{\texttt{--nmr\_inports}}
Replicate all top-level input ports. The resulting EDIF file will
have replicated input ports for every input port in the original design, with
names such as \texttt{inputPort\_TMR\_0}, \texttt{inputPort\_TMR\_1},
and \texttt{inputPort\_TMR\_2}.

\subsubsection{\texttt{--nmr\_outports}}
Force replication of all top-level output ports. The resulting EDIF file will
have replicated output ports for every output port in the original design, with
names such as \texttt{outputPort\_TMR\_0}, 
\texttt{outputPort\_TMR\_1}, and 
\texttt{outputPort\_TMR\_2}.

\subsubsection{\texttt{--no\_nmr\_p port1,port2,\ldots,portN}}
Prevent replication of specific top-level port(s), specified as a 
comma-separated list. Used in conjunction with \texttt{--nmr\_inports} and 
\texttt{--nmr\_outports}. For example, the following will replicate all input 
ports except the clock and reset ports, assuming \texttt{Clk} and \texttt{rst} 
are the (case-sensitive) names of the clock and reset input ports, respectively:

\texttt{--nmr\_inports --no\_nmr\_p Clk,rst}

\subsubsection{\texttt{--nmr\_c cell\_type1,cell\_type2,\ldots,cell\_typeN}}
Force replication of specific cell type(s), specified as a comma-separated list. 
All instances of the types specified will be replicated. \texttt{--nmr\_c}
takes precedence over \texttt{--no\_nmr\_c}. Mulitple \texttt{--nmr\_c} lists
may be specified.

Examples: 
\begin{itemize}
\item \texttt{--nmr\_c bufg,ibufg,fdc}
\item \texttt{--nmr\_c bufg,ibufg --nmr\_c fdc}
\end{itemize}

\subsubsection{\texttt{--nmr\_clk clock\_domain1,clock\_domain2,
\ldots,clock\_domainN}}
Force replication of the specified clock domain(s), specified as a
comma-separated list. Each clock domain should be specified with it's full
path, not including the top level instance name, each level being separated by '/' Note:
\texttt{--no\_nmr\_clk} takes precedence over \texttt{--nmr\_clk}. Multiple
\texttt{--nmr\_clk} lists may be specified.

\subsubsection{\texttt{--nmr\_i cell\_instance1,cell\_instance2,
\ldots,cell\_instanceN}}
Force replication of specific cell instance(s), specified as a comma-separated
list. 
Note: \texttt{--no\_nmr\_i} takes precedence over \texttt{--nmr\_i}. Multiple
\texttt{--nmr\_i} lists may be specified.
 
Example: \texttt{--nmr\_i clk\_bufg,multiplier16/adder16/fullAdder0}

\subsubsection{\texttt{--no\_nmr\_c cell\_type1,cell\_type2,\ldots,cell\_typeN}}
Prevent replication of specific cell type(s), specified as a comma-separated 
list. Multiple \texttt{--no\_nmr\_c} lists may be specified.

Example: \texttt{--no\_nmr\_c bufg,ibufg,fdc}

\subsubsection{\texttt{--no\_nmr\_clk clock\_domain1,
clock\_domain2,\ldots,clock\_domainN}}
Prevent replication of specified clock domain(s), specified as a comma-separated 
list. Multiple \texttt{--no\_nmr\_c} lists may be specified.

Example: \texttt{--no\_nmr\_clk clk\_c}


\subsubsection{\texttt{--no\_nmr\_i cell\_instance1,
cell\_instance2,\ldots,cell\_instanceN}}
Prevent replication of specific cell instance(s), specified as a 
comma-separated list. Multiple \texttt{--no\_nmr\_i} lists may be
specified.

Example: \texttt{--no\_nmr\_i clk\_bufg,multiplier16/adder16/fullAdder0}

\subsubsection{\texttt{--no\_nmr\_feedback}}
Skip replication of the feedback section of the design. 
Is it \emph{not} recommended to skip replication of the feedback section, as 
it is the most critical section for SEU mitigation.

\subsubsection{\texttt{--no\_nmr\_input\_to\_feedback}}
Skip replication of the portions of the design that ``feed into'' the feedback 
sections. These portions also contribute to the ``persistence'' of the design 
and should be included in replication, when possible.

\subsubsection{\texttt{--no\_nmr\_feedback\_output}}
Skip replication of the portions of the design which are driven by the 
feedback sections of the design.

\subsubsection{\texttt{--no\_nmr\_feed\_forward}}
Skip replication of the portions of the design which are not related to 
feedback sections (neither drive nor are driven by the feedback sections).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{SCC Options}
The following options control how BL-TMR handles strongly connected components 
(SCCs) and related logic. An SCC, by definition, is a maximal subgraph of
circuit components that are mutually reachable. That is, following the flow of
data, every component in the SCC can be reached from every other. In an SCC,
each component is related to every other component. The feedback section is
defined as the combination of all the strongly-connected components (SCCs). The
following options determine the order in which SCCs and related logic are
replicated as well as whether or not SCCs can be partitioned into smaller
components.

\subsubsection{\texttt{--ssc\_sort\_type} $\{1,2,3\}$}
Choose the method the BL-TMR tool uses to partially replicate logic in the 
``feedback'' section of the design.  Option 1 replicates the largest SCCs 
first. Option 2 replicates the smallest first. Option 3 replicates the SCCs 
in topological order.

This option only affects the resulting circuit if only some of the feedback 
section is replicated. If all or none of the ``feedback'' section is 
replicated, the three options produce identical results. The difference lies 
in what \emph{order} the logic in this section is added and thus what part of 
it is replicated if there are not enough resources available to replicate the 
entire section.

Valid options are \texttt{1}, \texttt{2}, and \texttt{3}. Default: \texttt{3}
(topological order).

\subsubsection{\texttt{--do\_scc\_decomposition}}
Allow portions of strongly-connected components (SCCs) to be included for 
replication. 

By default, if a single SCC is so large that it cannot be replicated for the 
target part, it is skipped. This option allows large SCCs to be broken up into 
smaller pieces, some of which may fit in the part. This is only useful if there 
are not enough resources to replicate the entire set of SCCs.

\subsubsection{\texttt{--input\_addition\_type} $\{1,2,3\}$}
Select between three different algorithms to partially replicate logic in the 
``input to feedback'' section of the design. Option 1 uses a depth-first search 
starting from the inputs to the feedback section. Option 3 uses a breadth-first 
search. Option 2 uses a combination of the two.

This option only affects the resulting circuit if only some of the input
to feedback section is replicated. If all or none of the input to feedback 
section is replicated, the three options produce identical results. The 
difference is in what \emph{order} the logic in this section is added and thus 
what part of it is replicated if there are not enough resources available to 
replicate the entire section.

Results may differ between the three addition types depending on the input 
design. It is yet not clear if one method is superior to the others in general. 

Valid options are \texttt{1}, \texttt{2}, and \texttt{3}. Default: \texttt{3} 
(breadth-first search).

\subsubsection{\texttt{--output\_addition\_type} $\{1,2,3\}$}
Similar to \texttt{--input\_addition\_type}, this option applies to the logic 
in the ``feedback output'' section, that is, logic that is driven by the
feedback section.

This option only affects the resulting circuit if only some of the feedback 
output section is replicated. It has no effect if all or none of the feedback 
output section is replicated. As with \texttt{--input\_addition\_type}, it is
yet not clear if one method is superior to the others in general.

Valid options are \texttt{1}, \texttt{2}, and \texttt{3}. Default: \texttt{3} 
(breadth-first search).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Merge Factor and Optimization Factor}
The following factors are used by the utilization tracker, which estimates the 
anticipated usage of the target chip after performing (partial) replication\@.
All factors in this section have the precision of a Java \texttt{double}. 

\subsubsection{\texttt{--merge\_factor} $\{ 0 \leq n \leq 1 \}$ }
Used to fine-tune the estimation of logic resources in the target chip. Each 
technology has an internal, default ``merge factor'' which estimates the 
percentage of LUTs and flip-flops that will share the same slice. As this 
factor is both technology and design dependent, this option allows the user to 
specify his/her own merge factor. 

The total number of logic blocks (without taking into account optimization) is 
given by the following equation:
\begin{equation*}
\mathrm{total~logic~blocks} = FFs + LUTs - (mergeFactor * FFs)
\end{equation*}

If you need to calculate a custom mergeFactor for a specific design, use the 
following equation:
\begin{equation*}
mergeFactor = \frac{(FFs + LUTs - 2 * slices)}{FFs}
\end{equation*}

Must be between 0 and 1, inclusive. Default: 0.5.

\subsubsection{\texttt{--optimization\_factor} $\{ 0 \leq n \leq 1 \}$}
The ``optimization factor'' is used to scale down the estimate of LUTs and 
flip-flops used to account for logic optimization performed during mapping. For 
example, an optimization factor of 0.90 would assume that logic optimization 
techniques would reduce the required number of LUTs and FFs by 10\%.

We define the optimization factor to be the number of logic blocks after 
optimization divided by the number of logic blocks before optimization.  So the 
final equation for the total number of logic blocks is as follows:
\begin{equation*}
\mathrm{Estimate} = optimization\_factor * (FFs + LUTs -  mergeFactor * FFs)
\end{equation*}

Must be between 0 and 1, inclusive. Default: 0.95.

\subsubsection{\texttt{--factor\_type} $\{ \mathtt{ASUF},\mathtt{UEF},\mathtt{DUF} \}$ }
Specify the Utilization Factor Type to be used. Valid Factor Types are:

\begin{itemize}
\item ASUF 

Available Space Utilization Factor: The maximum utilization of the target part,
expressed as a percentage of the unused space on the part after the original
(unreplicated) design has been considered.

\item UEF 

Utilization Expansion Factor: The maximum increase in utilization of the target
part, expressed as a percentage of the utilization of the original
(unreplicated) design.

\item DUF 

Desired Utilization Factor: The maximum percentage of the target chip to be
utilized after performing Partial replication.
\end{itemize}

Not case sensitive.

\subsubsection{\texttt{--factor\_value}}
Specify a single Factor Value.  The number has the precision of a Java 
\texttt{double} and is interpreted based on the Factor Type as explained above.

For example, if a design occupies 30\% of the target part prior to replication,
a DUF of 0.50 would use 50\% of the part. An UEF of 0.50 would increase the
usage by 50\%, resulting in 45\% usage of the part. An ASUF of 0.50 would use
50\% of the available space prior to replication, resulting in 65\% usage.

Must be greater than or equal to 0. Default: 1.0.

\subsubsection{\texttt{--ignore\_hard\_resource\_utilization\_limits}}
This option causes all hard resource utilization limits to be ignored when
determining how much of the design to replicate.

\subsubsection{\texttt{--ignore\_soft\_logic\_utilization\_limit}}
This option causes logic block utilization to be ignored when
determining how much of the design to replicate. Hard resources such as BRAMs
and CLKDLLs will still be tracked.

\input{option_Technology}
\input{option_ConfigFile}
\input{option_Logfile}

